3D Graphics Programming with QuickDraw 3D 1.5.4

Writing to Custom File Objects

Writing to custom file objects is done in two stages: the traversal stage, where the data to be written is set up, and the actual writing stage.

Traversal is done by the custom object's TQ3XObjectTraverseMethod or TQ3XObjectTraverseDataMethod :



 
typedef TQ3Status ( QD3D_CALLBACK 

                     *TQ3XObjectTraverseMethod)(

                     TQ3Object object,

                     void *data,

                     TQ3ViewObject view);

Writing is done by the custom object's TQ3XObjectWriteMethod :



 
typedefTQ3Status(QD3D_CALLBACK *TQ3XObjectWriteMethod)(

                     const void *object,

                     TQ3FileObject file);

The first part of the custom object's TQ3XObjectTraverseMethod traverses the root object. A metafile object always has a root object, which may or may not have one or more subobjects. The root object consists of all data that is not itself a QD3D object. All data in the form of QD3D objects must appear in the metafile as subobjects. For example, in a box the geometrical data (origin, orientation, and axes) makes up the root object. But the attribute sets (both face attribute sets and box attribute sets) are themselves QD3D objects, so they must be subobjects. If an object has subobjects, then the root and the subobjects are all contained in a container. If there are no subobjects, then no container is necessary.

The custom object's TQ3XObjectTraverseMethod computes the size of the root object and then calls Q3XView_SubmitWriteData once to traverse the root. After that, it can submit the subobjects, if any. It does this by making the public API call Q3Object_Submit on each subobject. As a shortcut, it can call the Q3XView_SubmitSubObjectData function.

If you need data from the view that's passed to the Q3View_StartWriting call that initiates the write loop, you must obtain it during your traverse routine (which is passed this view as argument). You cannot obtain data from the view during your write routine, since it does not take a view as argument and there is no other way to access the view from within it.

Note that your TQ3XObjectTraverseMethod can check some condition and, based on the result, decide not to write a particular part of the memory accessible from the data parameter in Q3XView_SubmitWriteData as part of the root object. It does this by not adding bytes to the size parameter. This decision must be mirrored in your TQ3XObjectWriteMethod method, where the corresponding Q3..._Write calls must be bypassed. The TQ3XObjectTraverseMethod can decide not to make any particular Q3Object_Submit call on a subobject, but this doesn't require any mirroring in the TQ3XObjectWriteMethod because Q3Object_Submit in the traverse method is all that's needed for writing a subobject. There is one special case: your traverse method can decide to write nothing at all by simply returning kQ3Success immediately. In that case the write method will never get called, so it doesn't need to do any checking of conditions.

Your TQ3XObjectWriteMethod consists of making any of the following calls (and no others) to write out the data of its root object. These calls are described in "Reading and Writing File Data" .



 
Q3Uns8_Write

Q3Uns16_Write

Q3Uns32_Write

Q3Int32_Write

Q3Uns64_Write

Q3Float32_Write

Q3Float64_Write

Q3Point2D_Write

Q3Point3D_Write

Q3RationalPoint3D_Write

Q3RationalPoint4D_Write

Q3Vector2D_Write

Q3Vector3D_Write

Q3Matrix4x4_Write

Q3Tangent2D_Write

Q3Tangent3D_Write

Q3NewLine_Write

Q3String_Write

Q3Size_Pad

Q3RawData_Write

Q3Comment_Write

The TQ3XObjectWriteMethod does nothing with subobjects; their roots are written by their own TQ3XObjectWriteMethod .

Q3XView_SubmitWriteData

You can use the Q3XView_SubmitWriteData function to write data to a custom file object.



 
TQ3Status Q3XView_SubmitWriteData(

                           TQ3ViewObject view,

                           TQ3Size size,

                           void *data,

                           TQ3XDataDeleteMethod deleteData);

view: A view.
size: The size of the data actually written.
data: A pointer to memory containing the data to be written.
deleteData: A TQ3XDataDeleteMethod method.

DESCRIPTION

The Q3XView_SubmitWriteData function writes the data pointed to by data, of size size, to the view view object. The deleteData parameter designates a method that disposes of memory allocations upon completion.

It is important that the size parameter matches the size of the data actually written. If this is not so, Q3XView_SubmitWriteData will fail.

The data pointer is later passed to your TQ3XObjectWriteMethod . Typically, it will point to a data structure, and your write routine will contain various calls from the family Q3Uns8_Write , Q3Uns32_Write , etc (see "Reading and Writing File Data" ), which will write to various fields in that data structure.

The deleteData parameter designates a TQ3XDataDeleteMethod . It is passed a pointer to your data structure, and it will delete whatever needs to be deleted (dispose of QD3D objects, deallocate memory, and so on). The delete method will be called upon exit of your write method whether or not your write method succeeded.

Q3XView_SubmitSubObjectData

You can use the Q3XView_SubmitSubObjectData function to write data to a custom file object more efficiently than you can with Q3XView_SubmitWriteData.



 
TQ3Status Q3XView_SubmitSubObjectData(

                     TQ3ViewObject view,

                     TQ3XObjectClass objectClass,

                     TQ3Size size,

                     void *data,

                     TQ3XDataDeleteMethod deleteData);

view: A view.
size: The size of the data actually written.
objectClass: An object class.
data: A pointer to memory containing the data to be written.
deleteData: A TQ3XDataDeleteMethod method.

DESCRIPTION

The Q3XView_SubmitSubObjectData function is a shortcut alternative to the Q3XView_SubmitWriteData function. It writes the data pointed to by data, of size size, to the view view object. The deleteData parameter designates a method that disposes of memory allocations upon completion.

You can use the Q3XView_SubmitSubObjectData function in the following situation. Suppose that your custom object C1 has another object of class S1 as a subobject in its metafile, and the only purpose for the existence of class S1 is to enable the writing and reading of these metafile subobjects. On the writing side, you don't need to create the object. You can just to do what's needed in a traverse method (pass its size and a pointer to the data), using Q3XView_SubmitSubObjectData . (Q3XView_SubmitSubObjectData also takes a TQ3XObjectClass as a parameter; this parameter is implicit in Q3XView_SubmitWriteData , where it is assumed to be the class of the root.) The traversal routine for C1 can call Q3XView_SubmitSubObjectData , where the data is C1's data structure, instead of having to first create an object of class S1 and then call Q3Object_Submit on that object. The write method for class S1 remains as it is with Q3XView_SubmitWriteData.